--- /dev/null
+# Compiling the GTK Libraries {#gtk-building}
+
+## Building GTK
+
+Before we get into the details of how to compile GTK, we should
+mention that in many cases, binary packages of GTK prebuilt for
+your operating system will be available, either from your
+operating system vendor or from independent sources. If such a
+set of packages is available, installing it will get you
+programming with GTK much faster than building it yourself. In
+fact, you may well already have GTK installed on your system already.
+
+In order to build GTK, you will need *meson* installed on your
+system. On Linux, and other UNIX-like operating systems, you will
+also need *ninja*. This guide does not cover how to install these
+two requirements, but you can refer to the
+[Meson website](http://mesonbuild.com) for more information. The
+[Ninja](https://ninja-build.org) build tool is also usable on
+various operating systems, so we will refer to it in the examples.
+
+If you are building GTK from a source distribution or from a Git
+clone, you will need to use *meson* to configure the project. The
+most commonly useful argument is the `--prefix` one, which determines
+where the files will go once installed. To install GTK under a prefix
+like `/opt/gtk` you would run Meson as:
+
+```
+meson setup --prefix /opt/gtk builddir
+```
+
+Meson will create the `builddir` directory and place all the build
+artefacts there.
+
+You can get a list of all available options for the build by
+running `meson configure`.
+
+After Meson successfully configured the build directory, you then
+can run the build, using Ninja:
+
+```
+cd builddir
+ninja
+ninja install
+```
+
+If you don't have permission to write to the directory you are
+installing in, you may have to change to root temporarily before
+running `ninja install`.
+
+Several environment variables are useful to pass to set before
+running *meson*. `CPPFLAGS` contains options to pass to the C
+compiler, and is used to tell the compiler where to look for
+include files. The `LDFLAGS` variable is used in a similar fashion
+for the linker. Finally the `PKG_CONFIG_PATH` environment variable
+contains a search path that `pkg-config` (see below) uses when
+looking for files describing how to compile programs using different
+libraries. If you were installing GTK and it's dependencies into
+`/opt/gtk`, you might want to set these variables as:
+
+```
+CPPFLAGS="-I/opt/gtk/include"
+LDFLAGS="-L/opt/gtk/lib"
+PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
+export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
+```
+
+You may also need to set the `LD_LIBRARY_PATH` environment variable
+so the systems dynamic linker can find the newly installed libraries,
+and the `PATH` environment program so that utility binaries installed
+by the various libraries will be found.
+
+```
+LD_LIBRARY_PATH="/opt/gtk/lib"
+PATH="/opt/gtk/bin:$PATH"
+export LD_LIBRARY_PATH PATH
+```
+
+## Build types {#build-types}
+
+Meson has different build types, exposed by the `buildtype`
+configuration option. GTK enables and disables functionality
+depending on the build type used when calling *meson* to
+configure the build.
+
+### Debug builds
+
+GTK will enable debugging code paths in both the `debug` and
+`debugoptimized` build types. Builds with `buildtype` set to
+`debug` will additionally enable consistency checks on the
+internal state of the toolkit.
+
+It is recommended to use the `debug` or `debugoptimized` build
+types when developing GTK itself. Additionally, `debug` builds of
+GTK are recommended for profiling and debugging GTK applications,
+as they include additional validation of the internal state.
+
+The `debugoptimized` build type is the default for GTK if no build
+type is specified when calling *meson*.
+
+### Release builds
+
+The `release` build type will disable debugging code paths and
+additional run time safeties, like checked casts for object
+instances.
+
+The `plain` build type provided by Meson should only be used when
+packaging GTK, and it's expected that packagers will provide their
+own compiler flags when building GTK. See the previous section for
+the list of environment variables to be used to define compiler and
+linker flags.
+
+## Dependencies {#dependencies}
+
+Before you can compile the GTK widget toolkit, you need to have
+various other tools and libraries installed on your
+system. Dependencies of GTK have their own build systems, so
+you will need to refer to their own installation instructions.
+
+A particular important tool used by GTK to find its dependencies
+is `pkg-config`.
+
+[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
+is a tool for tracking the compilation flags needed for libraries
+that are used by the GTK libraries. (For each library, a small `.pc`
+text file is installed in a standard location that contains the
+compilation flags needed for that library along with version number
+information.)
+
+Some of the libraries that GTK depends on are maintained by the
+GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
+Other libraries are maintained separately.
+
+- The GLib library provides core non-graphical functionality
+ such as high level data types, Unicode manipulation, and
+ an object and type system to C programs. It is available
+ from [here](https://download.gnome.org/sources/glib/).
+- The [GdkPixbuf](https://git.gnome.org/browse/gdk-pixbuf/)
+ library provides facilities for loading images in a variety of
+ file formats. It is available [here](ttps://download.gnome.org/sources/gdk-pixbuf/).
+- [Pango](http://www.pango.org) is a library for internationalized
+ text handling. It is available [here](https://download.gnome.org/sources/pango/).
+- ATK is the Accessibility Toolkit. It provides a set of generic
+ interfaces allowing accessibility technologies such as
+ screen readers to interact with a graphical user interface.
+ It is available [here](https://download.gnome.org/sources/atk/).
+- [GObject Introspection](https://wiki.gnome.org/Projects/GObjectIntrospection)
+ is a framework for making introspection data available to language
+ bindings. It is available [here](https://download.gnome.org/sources/gobject-introspection/).
+- The [GNU libiconv](https://www.gnu.org/software/libiconv/) library
+ is needed to build GLib if your system doesn't have the iconv()
+ function for doing conversion between character encodings. Most
+ modern systems should have iconv().
+- The libintl library from the [GNU gettext](https://www.gnu.org/software/gettext/)
+ package is needed if your system doesn't have the gettext()
+ functionality for handling message translation databases.
+- The libraries from the X window system are needed to build
+ Pango and GTK. You should already have these installed on
+ your system, but it's possible that you'll need to install
+ the development environment for these libraries that your
+ operating system vendor provides.
+- The [fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/)
+ library provides Pango with a standard way of locating
+ fonts and matching them against font names.
+- [Cairo](https://www.cairographics.org) is a graphics library that
+ supports vector graphics and image compositing. Both Pango and GTK
+ use Cairo for drawing.
+- [libepoxy](https://github.com/anholt/libepoxy) is a library that
+ abstracts the differences between different OpenGL libraries. GTK
+ uses it for cross-platform GL support and for its own drawing.
+- [Graphene](http://ebassi.github.io/graphene/) is a library that
+ provides vector and matrix types for 2D and 3D transformations.
+ GTK uses it internally for drawing.
+- The [Wayland](https://wayland.freedesktop.org) libraries are needed
+ to build GTK with the Wayland backend.
+- The [shared-mime-info](https://www.freedesktop.org/wiki/Software/shared-mime-info)
+ package is not a hard dependency of GTK, but it contains definitions
+ for mime types that are used by GIO and, indirectly, by GTK.
+ gdk-pixbuf will use GIO for mime type detection if possible.
+ For this to work, shared-mime-info needs to be installed and
+ `XDG_DATA_DIRS` set accordingly at configure time. Otherwise,
+ gdk-pixbuf falls back to its built-in mime type detection.
+
+## Building and testing GTK {#building}
+
+First make sure that you have the necessary external
+dependencies installed: `pkg-config`, Meson, Ninja,
+the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
+libiconv and libintl. To get detailed information about building
+these packages, see the documentation provided with the
+individual packages. On any average Linux system, it's quite likely
+you'll have all of these installed already, or they will be easily
+accessible through your operating system package repositories.
+
+Then build and install the GTK libraries in the order:
+GLib, Cairo, Pango, ATK, then GTK. For each library, follow the
+instructions they provide, and make sure to share common settings
+between them and the GTK build; if you are using a separate prefix
+for GTK, for instance, you will need to use the same prefix for
+all its dependencies you build. If you're lucky, this will all go
+smoothly, and you'll be ready to [start compiling your own GTK
+applications](#gtk-compiling). You can test your GTK installation
+by running the `gtk4-demo` program that GTK installs.
+
+If one of the projects you're configuring or building fails, look
+closely at the error messages printed; these will often provide useful
+information as to what went wrong. Every build system has its own
+log that can help you understand the issue you're encountering. If
+all else fails, you can ask for help on the
+[GTK forums](#gtk-resources).
+
+## Extra Configuration Options {#extra-configuration-options}
+
+In addition to the normal options provided by Meson,
+GTK defines various arguments that modify what should
+be built. All of these options are passed to `meson`
+as `-Doption=value`. Most of the time, the value can
+be `true` or `false`. To see a summary of all supported
+options and their allowed values, run
+```
+meson configure builddir
+```
+
+### `xinerama`
+
+By default GTK will try to link against the Xinerama libraries
+if they are found. This option can be used to explicitly control
+whether Xinerama should be used.
+
+### `gtk_doc` and `man-pages`
+
+The *gtk-doc* package is used to generate the reference documentation
+included with GTK. By default support for *gtk-doc* is disabled
+because it requires various extra dependencies to be installed.
+If you have *gtk-doc* installed and are modifying GTK, you may want
+to enable *gtk-doc* support by passing in `-Dgtk_doc=true`.
+
+Additionally, some tools provided by GTK have their own
+manual pages generated using a similar set of dependencies;
+if you have *xsltproc* then you can generate manual pages by
+passing `-Dman-pages=true` when configuring the build.
+
+### `print-backends`
+
+By default, GTK will try to build various print backends
+if their dependencies are found. This option can be used
+to explicitly control which print backends should be built.
+
+### `x11-backend`, `win32-backend`, `broadway-backend`, `wayland-backend` and `quartz-backend`
+
+Enable specific backends for GDK. If none of these options
+are given, the Wayland backend will be enabled by default,
+if the platform is Linux; the X11 backend will also be enabled
+by default, unless the platform is Windows, in which case the
+default is win32, or the platform is macOS, in which case the
+default is quartz. If any backend is explicitly enabled or disabled,
+no other platform will be enabled automatically.
+
+### `introspection`
+
+Allows to disable building introspection support. This is option
+is mainly useful for shortening turnaround times on developer
+systems. Installed builds of GTK should always have introspection
+support.
+
+### `build-tests`, `install-tests`, `demos`
+
+By default, GTK will build quite a few tests and demos.
+While these are useful on a developer system, they are not
+needed when GTK is built e.g. for a flatpak runtime. These
+options allow to disable building tests and demos.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-building">
-<refmeta>
-<refentrytitle>Compiling the GTK libraries</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling the GTK Libraries</refname>
-<refpurpose>
-How to compile GTK itself
-</refpurpose>
-</refnamediv>
- <refsect1 id="overview">
- <title>Building GTK</title>
- <para>
- Before we get into the details of how to compile GTK, we should
- mention that in many cases, binary packages of GTK prebuilt for
- your operating system will be available, either from your
- operating system vendor or from independent sources. If such a
- set of packages is available, installing it will get you
- programming with GTK much faster than building it yourself. In
- fact, you may well already have GTK installed on your system
- already.
- </para>
- <para>
- In order to build GTK, you will need <application>meson</application>
- installed on your system. On Linux, and other UNIX-like operating
- systems, you will also need <application>ninja</application>. This
- guide does not cover how to install these two requirements, but you
- can refer to the <ulink url="http://mesonbuild.com">Meson website</ulink>
- for more information. The <ulink url="https://ninja-build.org">Ninja</ulink>
- build tool is also usable on various operating systems, so we will
- refer to it in the examples.
- </para>
- <para>
- If you are building GTK from a source distribution or from a Git
- clone, you will need to use <application>meson</application> to
- configure the project. The most commonly useful argument is the
- <systemitem>--prefix</systemitem> one, which determines where the
- files will go once installed. To install GTK under a prefix
- like <filename>/opt/gtk</filename> you would run Meson as:
- </para>
- <informalexample>
- <programlisting>
- meson setup --prefix /opt/gtk builddir
- </programlisting>
- </informalexample>
- <para>
- Meson will create the <filename>builddir</filename> directory and
- place all the build artefacts there.
- </para>
- <para>
- You can get a list of all available options for the build by
- running <application>meson configure</application>.
- </para>
- <para>
- After Meson successfully configured the build directory, you then
- can run the build, using Ninja:
- </para>
- <informalexample>
- <programlisting>
- cd builddir
- ninja
- ninja install
- </programlisting>
- </informalexample>
- <para>
- If you don't have permission to write to the directory you are
- installing in, you may have to change to root temporarily before
- running <literal>ninja install</literal>.
- </para>
- <para>
- Several environment variables are useful to pass to set before
- running <application>meson</application>. <envar>CPPFLAGS</envar>
- contains options to pass to the C compiler, and is used to tell
- the compiler where to look for include files. The <envar>LDFLAGS</envar>
- variable is used in a similar fashion for the linker. Finally the
- <envar>PKG_CONFIG_PATH</envar> environment variable contains
- a search path that <command>pkg-config</command> (see below)
- uses when looking for files describing how to compile
- programs using different libraries. If you were installing GTK
- and it's dependencies into <filename>/opt/gtk</filename>, you
- might want to set these variables as:
- </para>
- <programlisting>
- CPPFLAGS="-I/opt/gtk/include"
- LDFLAGS="-L/opt/gtk/lib"
- PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
- export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
- </programlisting>
- <para>
- You may also need to set the <envar>LD_LIBRARY_PATH</envar>
- environment variable so the systems dynamic linker can find
- the newly installed libraries, and the <envar>PATH</envar>
- environment program so that utility binaries installed by
- the various libraries will be found.
- </para>
- <programlisting>
- LD_LIBRARY_PATH="/opt/gtk/lib"
- PATH="/opt/gtk/bin:$PATH"
- export LD_LIBRARY_PATH PATH
- </programlisting>
- </refsect1>
-
- <refsect1 id="build-types">
- <title>Build types</title>
-
- <para>Meson has different build types, exposed by the <literal>buildtype</literal>
- configuration option. GTK enables and disables functionality depending on
- the build type used when calling <application>meson</application> to
- configure the build.</para>
-
- <formalpara>
- <title><systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem></title>
-
- <para>
- GTK will enable debugging code paths in both the
- <literal>debug</literal> and <literal>debugoptimized</literal>
- build types. Builds with <literal>buildtype</literal> set
- to <literal>debug</literal> will additionally enable
- consistency checks on the internal state of the toolkit.
- </para>
-
- <para>
- It is recommended to use the <literal>debug</literal> or
- <literal>debugoptimized</literal> build types when developing
- GTK itself. Additionally, <literal>debug</literal> builds of
- GTK are recommended for profiling and debugging GTK applications,
- as they include additional validation of the internal state.
- </para>
-
- <para>
- The <literal>debugoptimized</literal> build type is the
- default for GTK if no build type is specified when calling
- <application>meson</application>
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>release</systemitem></title>
-
- <para>
- The <literal>release</literal> build type will disable
- debugging code paths and additional run time safeties, like
- checked casts for object instances.
- </para>
- </formalpara>
-
- <para>
- The <literal>plain</literal> build type provided by Meson
- should only be used when packaging GTK, and it's expected
- that packagers will provide their own compiler flags when
- building GTK. See the previous section for the list of
- environment variables to be used to define compiler and
- linker flags.
- </para>
- </refsect1>
-
- <refsect1 id="dependencies">
- <title>Dependencies</title>
- <para>
- Before you can compile the GTK widget toolkit, you need to have
- various other tools and libraries installed on your
- system. Dependencies of GTK have their own build systems, so
- you will need to refer to their own installation instructions.
- </para>
- <para>
- A particular important tool used by GTK to find its dependencies
- is <application>pkg-config</application>.
- </para>
- <para>
- <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
- is a tool for tracking the compilation flags needed for
- libraries that are used by the GTK libraries. (For each
- library, a small <literal>.pc</literal> text file is installed
- in a standard location that contains the compilation flags
- needed for that library along with version number information.)
- </para>
- <para>
- Some of the libraries that GTK depends on are maintained by
- by the GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
- Other libraries are maintained separately.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The GLib library provides core non-graphical functionality
- such as high level data types, Unicode manipulation, and
- an object and type system to C programs. It is available
- from <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://git.gnome.org/browse/gdk-pixbuf/">GdkPixbuf library</ulink>
- provides facilities for loading images in a variety of file formats.
- It is available <ulink url="https://download.gnome.org/sources/gdk-pixbuf/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.pango.org">Pango</ulink> is a library
- for internationalized text handling. It is available
- <ulink url="https://download.gnome.org/sources/pango/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- ATK is the Accessibility Toolkit. It provides a set of generic
- interfaces allowing accessibility technologies such as
- screen readers to interact with a graphical user interface.
- It is available
- <ulink url="https://download.gnome.org/sources/atk/">here</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://wiki.gnome.org/Projects/GObjectIntrospection">Gobject Introspection</ulink>
- is a framework for making introspection data available to
- language bindings. It is available
- <ulink url="https://download.gnome.org/sources/gobject-introspection/">here</ulink>.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <title>External dependencies</title>
- <listitem>
- <para>
- The <ulink url="https://www.gnu.org/software/libiconv/">GNU
- libiconv library</ulink> is needed to build GLib if your
- system doesn't have the <function>iconv()</function>
- function for doing conversion between character
- encodings. Most modern systems should have
- <function>iconv()</function>.
- </para>
- </listitem>
- <listitem>
- <para>
- The libintl library from the <ulink
- url="https://www.gnu.org/software/gettext/">GNU gettext
- package</ulink> is needed if your system doesn't have the
- <function>gettext()</function> functionality for handling
- message translation databases.
- </para>
- </listitem>
- <listitem>
- <para>
- The libraries from the X window system are needed to build
- Pango and GTK. You should already have these installed on
- your system, but it's possible that you'll need to install
- the development environment for these libraries that your
- operating system vendor provides.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</ulink>
- library provides Pango with a standard way of locating
- fonts and matching them against font names.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://www.cairographics.org">Cairo</ulink>
- is a graphics library that supports vector graphics and image
- compositing. Both Pango and GTK use Cairo for drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://github.com/anholt/libepoxy">libepoxy</ulink>
- is a library that abstracts the differences between different
- OpenGL libraries. GTK uses it for cross-platform GL support
- and for its own drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="https://github.com/anholt/libepoxy">Graphene</ulink>
- is a library that provides vector and matrix types for 2D and
- 3D transformations. GTK uses it internally for drawing.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://wayland.freedesktop.org">Wayland</ulink> libraries
- are needed to build GTK with the Wayland backend.
- </para>
- </listitem>
- <listitem>
- <para>
- The <ulink url="https://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
- package is not a hard dependency of GTK, but it contains definitions
- for mime types that are used by GIO and, indirectly, by GTK.
- gdk-pixbuf will use GIO for mime type detection if possible. For this
- to work, shared-mime-info needs to be installed and
- <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
- Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
- </para>
- </listitem>
- </itemizedlist>
- </refsect1>
- <refsect1 id="building">
- <title>Building and testing GTK</title>
- <para>
- First make sure that you have the necessary external
- dependencies installed: <command>pkg-config</command>, Meson, Ninja,
- the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
- libiconv and libintl. To get detailed information about building
- these packages, see the documentation provided with the
- individual packages. On any average Linux system, it's quite likely
- you'll have all of these installed already, or they will be easily
- accessible through your operating system package repositories.
- </para>
- <para>
- Then build and install the GTK libraries in the order:
- GLib, Cairo, Pango, ATK, then GTK. For each library, follow the
- instructions they provide, and make sure to share common settings
- between them and the GTK build; if you are using a separate prefix
- for GTK, for instance, you will need to use the same prefix for all
- its dependencies you build. If you're lucky, this will all go smoothly,
- and you'll be ready to <link linkend="gtk-compiling">start compiling
- your own GTK applications</link>. You can test your GTK installation
- by running the <command>gtk4-demo</command> program that
- GTK installs.
- </para>
- <para>
- If one of the projects you're configuring or building fails, look
- closely at the error messages printed; these will often provide useful
- information as to what went wrong. Every build system has its own
- log that can help you understand the issue you're encountering. If all
- else fails, you can ask for help on the gtk-list mailing list.
- See <xref linkend="gtk-resources"/> for more information.
- </para>
- </refsect1>
-
- <refsect1 id="extra-configuration-options">
- <title>Extra Configuration Options</title>
-
- <para>
- In addition to the normal options provided by Meson, GTK defines
- various arguments that modify what should be built.
-
- <cmdsynopsis>
- <command>meson</command>
- <sbr/>
- <group>
- <arg choice="plain">-Dx11-backend=true</arg>
- <arg choice="plain">-Dx11-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dwayland-backend=true</arg>
- <arg choice="plain">-Dwayland-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dbroadway-backend=true</arg>
- <arg choice="plain">-Dbroadway-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dwin32-backend=true</arg>
- <arg choice="plain">-Dwin32-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dquartz-backend=true</arg>
- <arg choice="plain">-Dquartz-backend=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dmedia=gstreamer</arg>
- <arg choice="plain">-Dmedia=ffmpeg</arg>
- <arg choice="plain">-Dmedia=all</arg>
- <arg choice="plain">-Dmedia=none</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dvulkan=yes</arg>
- <arg choice="plain">-Dvulkan=no</arg>
- <arg choice="plain">-Dvulkan=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dxinerama=yes</arg>
- <arg choice="plain">-Dxinerama=no</arg>
- <arg choice="plain">-Dxinerama=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dcloudproviders=true</arg>
- <arg choice="plain">-Dcloudproviders=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dprint-backends=all</arg>
- <arg choice="plain">-Dprint-backends=none</arg>
- <arg choice="plain">-Dprint-backends=cups,lpr,...</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dcolord=yes</arg>
- <arg choice="plain">-Dcolord=no</arg>
- <arg choice="plain">-Dcolord=auto</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dgtk_doc=true</arg>
- <arg choice="plain">-Dgtk_doc=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dman-pages=true</arg>
- <arg choice="plain">-Dman-pages=false</arg>
- </group>
- <sbr/>
- <group>
- <arg choice="plain">-Dintrospection=true</arg>
- <arg choice="plain">-Dintrospection=false</arg>
- </group>
- </cmdsynopsis>
- </para>
-
- <formalpara>
- <title><systemitem>xinerama</systemitem></title>
-
- <para>
- By default GTK will try to link against the Xinerama libraries
- if they are found. This options can be used to explicitly control
- whether Xinerama should be used.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>gtk_doc</systemitem> and
- <systemitem>man-pages</systemitem></title>
-
- <para>
- The <application>gtk-doc</application> package is
- used to generate the reference documentation included
- with GTK. By default support for <application>gtk-doc</application>
- is disabled because it requires various extra dependencies
- to be installed. If you have
- <application>gtk-doc</application> installed and
- are modifying GTK, you may want to enable
- <application>gtk-doc</application> support by passing
- in <systemitem>gtk_doc</systemitem>.
- </para>
- <para>
- Additionally, some tools provided by GTK have their own
- manual pages generated using a similar set of dependencies;
- if you have <application>xsltproc</application> then you
- can generate manual pages by passing <systemitem>man-pages</systemitem>
- when configuring the build.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>print-backends</systemitem></title>
-
- <para>
- By default, GTK will try to build various print backends if
- their dependencies are found. This option can be used to
- explicitly control which print backends should be built.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>x11-backend</systemitem>,
- <systemitem>win32-backend</systemitem>,
- <systemitem>quartz-backend</systemitem>,
- <systemitem>broadway-backend</systemitem> and
- <systemitem>wayland-backend</systemitem></title>
-
- <para>
- Enable specific backends for GDK. If none of these options
- are given, the Wayland backend will be enabled by default,
- if the platform is Linux; the X11 backend will also be enabled
- by default, unless the platform is Windows, in which case the
- default is win32, or the platform is macOS, in which case the
- default is quartz. If any backend is explicitly enabled or disabled,
- no other platform will be enabled automatically.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>introspection</systemitem></title>
-
- <para>
- Allows to disable building introspection support. This is option
- is mainly useful for shortening turnaround times on developer
- systems. Installed builds of GTK should always have introspection
- support.
- </para>
- </formalpara>
-
- <formalpara>
- <title><systemitem>build-tests</systemitem>,
- <systemitem>install-tests</systemitem>,
- <systemitem>demos</systemitem></title>
-
- <para>
- By default, GTK will build quite a few tests and demos.
- While these are useful on a developer system, they are not
- needed when GTK is built e.g. for a flatpak runtime. These
- options allow to disable building tests and demos.
- </para>
- </formalpara>
-
- </refsect1>
-
-</refentry>
--- /dev/null
+# Compiling GTK Applications on UNIX {#gtk-compiling}
+
+To compile a GTK application, you need to tell the compiler where to
+find the GTK header files and libraries. This is done with the
+`pkg-config` utility.
+
+The following interactive shell session demonstrates how `pkg-config`
+is used (the actual output on your system may be different):
+
+```
+$ pkg-config --cflags gtk4
+ -pthread -I/usr/include/gtk-4.0 -I/usr/lib64/gtk-4.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
+$ pkg-config --libs gtk4
+ -pthread -lgtk-4 -lgdk-4 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
+```
+The simplest way to compile a program is to use the "backticks"
+feature of the shell. If you enclose a command in backticks
+(*not single quotes*), then its output will be substituted into the
+command line before execution. So to compile a GTK Hello, World, you
+would type the following:
+```
+$ cc `pkg-config --cflags gtk4` hello.c -o hello `pkg-config --libs gtk4`
+```
+Deprecated GTK functions are annotated to make the compiler
+emit warnings when they are used (e.g. with gcc, you need to use
+the -Wdeprecated-declarations option). If these warnings are
+problematic, they can be turned off by defining the preprocessor
+symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
+option `-DGDK_DISABLE_DEPRECATION_WARNINGS`.
+
+GTK deprecation annotations are versioned; by defining the
+macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
+you can specify the range of GTK versions whose API you want
+to use. APIs that were deprecated before or introduced after
+this range will trigger compiler warnings.
+
+Here is how you would compile hello.c if you want to allow it
+to use symbols that were not deprecated in 4.2:
+```
+$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
+```
+
+And here is how you would compile hello.c if you don't want
+it to use any symbols that were introduced after 4.2:
+```
+$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
+```
+The older deprecation mechanism of hiding deprecated interfaces
+entirely from the compiler by using the preprocessor symbol
+GTK_DISABLE_DEPRECATED is still used for deprecated macros,
+enumeration values, etc. To detect uses of these in your code,
+use the commandline option `-DGTK_DISABLE_DEPRECATED`.
+There are similar symbols GDK_DISABLE_DEPRECATED,
+GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK,
+GdkPixbuf and GLib.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-compiling">
-<refmeta>
-<refentrytitle>Compiling GTK Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling GTK Applications</refname>
-<refpurpose>
-How to compile your GTK application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Compiling GTK Applications on UNIX</title>
-
-<para>
-To compile a GTK application, you need to tell the compiler where to
-find the GTK header files and libraries. This is done with the
-<literal>pkg-config</literal> utility.
-</para>
-<para>
-The following interactive shell session demonstrates how
-<literal>pkg-config</literal> is used (the actual output on
-your system may be different):
-<programlisting>
-$ pkg-config --cflags gtk4
- -pthread -I/usr/include/gtk-4.0 -I/usr/lib64/gtk-4.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12
-$ pkg-config --libs gtk4
- -pthread -lgtk-4 -lgdk-4 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
-</programlisting>
-</para>
-<para>
-The simplest way to compile a program is to use the "backticks"
-feature of the shell. If you enclose a command in backticks
-(<emphasis>not single quotes</emphasis>), then its output will be
-substituted into the command line before execution. So to compile
-a GTK Hello, World, you would type the following:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-Deprecated GTK functions are annotated to make the compiler
-emit warnings when they are used (e.g. with gcc, you need to use
-the -Wdeprecated-declarations option). If these warnings are
-problematic, they can be turned off by defining the preprocessor
-symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
-option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
-</para>
-
-<para>
-GTK deprecation annotations are versioned; by defining the
-macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
-you can specify the range of GTK versions whose API you want
-to use. APIs that were deprecated before or introduced after
-this range will trigger compiler warnings.
-</para>
-
-<para>
-Here is how you would compile hello.c if you want to allow it
-to use symbols that were not deprecated in 4.2:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MIN_REQIRED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-And here is how you would compile hello.c if you don't want
-it to use any symbols that were introduced after 4.2:
-<programlisting>
-$ cc `pkg-config --cflags gtk4` -DGDK_VERSION_MAX_ALLOWED=GDK_VERSION_4_2 hello.c -o hello `pkg-config --libs gtk4`
-</programlisting>
-</para>
-
-<para>
-The older deprecation mechanism of hiding deprecated interfaces
-entirely from the compiler by using the preprocessor symbol
-GTK_DISABLE_DEPRECATED is still used for deprecated macros,
-enumeration values, etc. To detect uses of these in your code,
-use the commandline option <literal>-DGTK_DISABLE_DEPRECATED</literal>.
-There are similar symbols GDK_DISABLE_DEPRECATED,
-GDK_PIXBUF_DISABLE_DEPRECATED and G_DISABLE_DEPRECATED for GDK, GdkPixbuf and
-GLib.
-</para>
-
-</refsect1>
-</refentry>
<part id="platform-support">
<title>GTK Platform Support</title>
<xi:include href="building.xml" />
- <xi:include href="xml/compiling.xml" />
+ <xi:include href="compiling.xml" />
<xi:include href="running.xml" />
<xi:include href="x11.xml" />
<xi:include href="windows.xml" />
content_files = [
'broadway.xml',
- 'building.xml',
- 'compiling.xml',
'glossary.xml',
'gtk4-broadwayd.xml',
'gtk4-builder-tool.xml',
'overview.xml',
'question_index.xml',
'resources.xml',
- 'running.xml',
'text_widget.xml',
'tree_widget.xml',
'visual_index.xml',
]
expand_content_files = [
- 'compiling.xml',
'glossary.xml',
'question_index.xml',
'text_widget.xml',
]
expand_content_md_files = [
+ 'building.md',
+ 'compiling.md',
+ 'running.md',
'migrating-2to4.md',
'migrating-3to4.md',
'actions.md',
--- /dev/null
+# Running and debugging GTK Applications {#gtk-running}
+
+## Environment variables
+
+GTK inspects a number of environment variables in addition to
+standard variables like `LANG`, `PATH`, `HOME` or `DISPLAY`; mostly
+to determine paths to look for certain files. The [X11]{#x11-envar},
+[Windows]{#win32-envar} and [Broadway]{#broadway-envar} GDK backends
+use some additional environment variables.
+
+### GTK_DEBUG {#GTK_Debug-Options}
+
+Unless GTK has been configured with `-Ddebug=false`, this variable
+can be set to a list of debug options, which cause GTK to print out
+different types of debugging information.
+
+actions
+ : Actions and menu models
+builder
+ : GtkBuilder support
+geometry
+ : Size allocation
+icontheme
+ : Icon themes
+keybindings
+ : Keybindings
+modules
+ : Loading of modules
+printing
+ : Printing support
+size-request
+ : Size requests
+text
+ : Text widget internals
+tree
+ : Tree widget internals
+
+ A number of keys are influencing behavior instead of just logging:
+
+interactive
+ : Open the [interactive debugger](#interactive-debugging)
+no-css-cache
+ : Bypass caching for CSS style properties
+touchscreen
+ : Pretend the pointer is a touchscreen device
+updates
+ : Visual feedback about window updates
+resize
+ : Highlight resizing widgets
+layout
+ : Show layout borders
+snapshot
+ : Include debug render nodes in the generated snapshots
+
+The special value `all` can be used to turn on all debug options.
+The special value `help` can be used to obtain a list of all
+supported debug options.
+
+### GTK_PATH {#gtk-path}
+
+Specifies a list of directories to search when GTK is looking for
+dynamically loaded objects such as input method modules and print
+backends. If the path to the dynamically loaded object is given as
+an absolute path name, then GTK loads it directly. Otherwise, GTK
+goes in turn through the directories in `GTK_PATH`, followed by
+the directory `.gtk-4.0` in the user's home directory, followed
+by the system default directory, which is `libdir/gtk-4.0/modules`.
+(If `GTK_EXE_PREFIX` is defined, `libdir` is `$GTK_EXE_PREFIX/lib`.
+Otherwise it is the libdir specified when GTK was configured, usually
+`/usr/lib`, or `/usr/local/lib`.)
+
+For each directory in this list, GTK actually looks in a subdirectory
+`directory/version/host/type`. Where `version` is derived from the
+version of GTK (use `pkg-config --variable=gtk_binary_version gtk4`
+to determine this from a script), `host` is the architecture on
+which GTK was built. (use `pkg-config --variable=gtk_host gtk4` to
+determine this from a script), and `type` is a directory specific to
+the type of modules; currently it can be `modules`, `immodules` or
+`printbackends`, corresponding to the types of modules mentioned
+above. Either `version`, `host`, or both may be omitted. GTK looks
+first in the most specific directory, then in directories with
+fewer components.
+The components of `GTK_PATH` are separated by the ':' character on
+Linux and Unix, and the ';' character on Windows.
+
+Note that this environment variable is read by GTK 2.x and GTK 3.x
+too, which makes it unsuitable for setting it system-wide (or
+session-wide), since doing so will cause applications using
+different GTK versions to see incompatible modules.
+
+### GTK_IM_MODULE
+
+Specifies an IM module to use in preference to the one determined
+from the locale. If this isn't set and you are running on the system
+that enables `XSETTINGS` and has a value in `Gtk/IMModule`, that will
+be used for the default IM module. This also can be a colon-separated
+list of input-methods, which GTK will try in turn until it finds one
+available on the system.
+
+### GTK_EXE_PREFIX
+
+If set, GTK uses `$GTK_EXE_PREFIX/lib` instead of the libdir
+configured when GTK was compiled.
+
+### GTK_DATA_PREFIX
+
+If set, GTK uses `$GTK_DATA_PREFIX` instead of the prefix
+configured when GTK was compiled.
+
+### GTK_THEME
+
+If set, makes GTK use the named theme instead of the theme
+that is specified by the gtk-theme-name setting. This is intended
+mainly for easy debugging of theme issues.
+
+It is also possible to specify a theme variant to load, by appending
+the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`.
+
+The following environment variables are used by GdkPixbuf, GDK or
+Pango, not by GTK itself, but we list them here for completeness
+nevertheless.
+
+### GDK_PIXBUF_MODULE_FILE
+
+Specifies the file listing the GdkPixbuf loader modules to load.
+This environment variable overrides the default value
+`libdir/gtk-4.0/4.0.0/loaders.cache` (`libdir` is the sysconfdir
+specified when GTK was configured, usually `/usr/lib`.)
+
+The `loaders.cache` file is generated by the
+`gdk-pixbuf-query-loaders` utility.
+
+### GDK_DEBUG
+
+Unless GTK has been configured with `-Ddebug=false`, this variable
+can be set to a list of debug options, which cause GDK to print out
+different types of debugging information.
+
+cursor
+ : Information about cursor objects (only win32)
+eventloop
+ : Information about event loop operation (mostly Quartz)
+misc
+ : Miscellaneous information
+frames
+ : Information about the frame clock
+settings
+ : Information about xsettings
+selection
+ : Information about selections
+clipboard
+ : Information about clipboards
+dnd
+ : Information about drag-and-drop
+opengl
+ : Information about OpenGL
+vulkan
+ : Information about Vulkan
+
+A number of options affect behavior instead of logging:
+
+nograbs
+ : Turn off all pointer and keyboard grabs
+gl-disable
+ : Disable OpenGL support
+gl-software
+ : Force OpenGL software rendering
+gl-texture-rect
+ : Use the OpenGL texture rectangle extension, if available
+gl-legacy
+ : Use a legacy OpenGL context
+gl-gles
+ : Use a GLES OpenGL context
+vulkan-disable
+ : Disable Vulkan support
+vulkan-validate
+ : Load the Vulkan validation layer, if available
+
+The special value `all` can be used to turn on all
+debug options. The special value `help` can be used
+to obtain a list of all supported debug options.
+
+### GSK_DEBUG {#GSK-Debug-Options}
+
+Unless GTK has been configured with `-Ddebug=false`,
+this variable can be set to a list of debug options,
+which cause GSK to print out different types of debugging
+information.
+
+renderer
+ : General renderer information
+cairo
+ : cairo renderer information
+opengl
+ : OpenGL renderer information
+shaders
+ : Shaders
+surface
+ : Surfaces
+vulkan
+ : Vulkan renderer information
+fallback
+ : Information about fallbacks
+glyphcache
+ : Information about glyph caching
+
+ A number of options affect behavior instead of logging:
+
+diff
+ : Show differences
+geometry
+ : Show borders
+full-redraw
+ : Force full redraws for every frame
+sync
+ : Sync after each frame
+vulkan-staging-image
+ : Use a staging image for Vulkan texture upload
+vulkan-staging-buffer
+ : Use a staging buffer for Vulkan texture upload
+
+The special value `all` can be used to turn on all
+debug options. The special value `help` can be used
+to obtain a list of all supported debug options.
+
+### GDK_BACKEND
+
+If set, selects the GDK backend to use. Selecting a backend
+requires that GTK is compiled with support for that backend.
+The following backends can be selected, provided they are
+included in the GDK libraries you are using:
+
+quartz
+ : Selects the native Quartz backend
+win32
+ : Selects the native backend for Microsoft Windows
+x11
+ : Selects the native backend for connecting to X11 servers
+broadway
+ : Selects the Broadway backend for display in web browsers
+wayland
+ : Selects the Wayland backend for connecting to Wayland compositors
+
+This environment variable can contain a comma-separated list of
+backend names, which are tried in order. The list may also contain
+a *, which means: try all remaining backends. The special value
+`help` can be used to make GDK print out a list of all available
+backends. For more information about selecting backends,
+see the gdk_display_manager_get() function.
+
+### GDK_VULKAN_DEVICE
+
+This variable can be set to the index of a Vulkan device to override
+the default selection of the device that is used for Vulkan rendering.
+The special value `list` can be used to obtain a list of all Vulkan
+devices.
+
+### GSK_RENDERER
+
+If set, selects the GSK renderer to use. The following renderers can
+be selected, provided they are included in the GTK library you are
+using and the GDK backend supports them:
+
+help
+ : Prints information about available options
+broadway
+ : Selects the Broadway-backend specific renderer
+cairo
+ : Selects the fallback Cairo renderer
+gl
+ : Selects the default OpenGL renderer
+vulkan
+ : Selects the Vulkan renderer
+
+### GTK_CSD
+
+The default value of this environment variable is 1. If changed
+to 0, this disables the default use of client-side decorations
+on GTK windows, thus making the window manager responsible for
+drawing the decorations of windows that do not have a custom
+titlebar widget.
+
+CSD is always used for windows with a custom titlebar widget set,
+as the WM should not draw another titlebar or other decorations
+around the custom one.
+
+### XDG_DTA_HOME, XDG_DATA_DIRS
+
+GTK uses these environment variables to locate icon themes
+and MIME information. For more information, see the
+[Icon Theme Specification](https://freedesktop.org/Standards/icon-theme-spec)
+the [Shared MIME-Info Database](https://freedesktop.org/Standards/shared-mime-info-spec)
+and the [Base Directory Specification](https://freedesktop.org/Standards/basedir-spec).
+
+### DESKTOP_STARTUP_ID
+
+GTK uses this environment variable to provide startup notification
+according to the [Startup Notification Spec](https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
+Following the specification, GTK unsets this variable after reading
+it (to keep it from leaking to child processes). So, if you need its
+value for your own purposes, you have to read it before calling
+gtk_init().
+
+## Interactive debugging {#interactive-debugging}
+
+
+
+GTK includes an interactive debugger, called the GTK Inspector, which
+lets you explore the widget tree of any GTK application at runtime,
+as well as tweak the theme and trigger visual debugging aids. You can
+easily try out changes at runtime before putting them into the code.
+
+Note that the GTK inspector can only show GTK internals. It can not
+understand the application-specific logic of a GTK application. Also,
+the fact that the GTK inspector is running in the application process
+limits what it can do. It is meant as a complement to full-blown
+debuggers and system tracing facilities such as DTrace, not as a
+replacement.
+
+To enable the GTK inspector, you can use the Control-Shift-I or
+Control-Shift-D keyboard shortcuts, or set the `GTK_DEBUG=interactive`
+environment variable.
+
+There are a few more environment variables that can be set to influence
+how the inspector renders its UI. `GTK_INSPECTOR_DISPLAY` and
+`GTK_INSPECTOR_RENDERER` determine the GDK display and the GSK
+renderer that the inspector is using.
+
+In some situations, it may be inappropriate to give users access to
+the GTK inspector. The keyboard shortcuts can be disabled with the
+`enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
+GSettings schema.
+
+## Profiling {#profiling}
+
+GTK supports profiling with sysprof. It exports timing information
+about frameclock phases and various characteristics of GskRenders
+in a format that can be displayed by sysprof or GNOME Builder.
+
+A simple way to capture data is to set the `GTK_TRACE` environment
+variable. When it is set, GTK will write profiling data to a file
+called `gtk.PID.syscap`.
+
+When launching the application from sysprof, it will set the
+`SYSPROF_TRACE_FD` environment variable to point GTK at a file
+descriptor to write profiling data to.
+
+When GtkApplication registers with D-Bus, it exports the
+`org.gnome.Sysprof2.Profiler` D-Bus interface that lets sysprof
+request profiling data at runtime.
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-running">
-<refmeta>
-<refentrytitle>Running GTK Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Running GTK Applications</refname>
-<refpurpose>
-How to run and debug your GTK application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Running and debugging GTK Applications</title>
-
-<refsect2>
-<title>Environment variables</title>
-
-<para>
-GTK inspects a number of environment variables in addition to standard
-variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar>
-or <envar>DISPLAY</envar>; mostly to determine paths to look for certain
-files. The <link linkend="x11-envar">X11</link>,
-<link linkend="win32-envar">Windows</link> and
-<link linkend="broadway-envar">Broadway</link> GDK backends use some
-additional environment variables.
-</para>
-
-<formalpara id="GTK-Debug-Options">
- <title><envar>GTK_DEBUG</envar></title>
-
- <para>
- Unless GTK has been configured with <option>-Ddebug=false</option>,
- this variable can be set to a list of debug options, which cause GTK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>actions</term>
- <listitem><para>Actions and menu models</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>builder</term>
- <listitem><para>GtkBuilder support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>geometry</term>
- <listitem><para>Size allocation</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>icontheme</term>
- <listitem><para>Icon themes</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>keybindings</term>
- <listitem><para>Keybindings</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>modules</term>
- <listitem><para>Loading of modules</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>printing</term>
- <listitem><para>Printing support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>size-request</term>
- <listitem><para>Size requests</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>text</term>
- <listitem><para>Text widget internals</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>tree</term>
- <listitem><para>Tree widget internals</para></listitem>
- </varlistentry>
- </variablelist>
- A number of keys are influencing behavior instead of just logging:
- <variablelist>
- <varlistentry>
- <term>interactive</term>
- <listitem><para>Open the <link linkend="interactive-debugging">interactive debugger</link></para></listitem>
- </varlistentry>
- <varlistentry>
- <term>no-css-cache</term>
- <listitem><para>Bypass caching for CSS style properties</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>touchscreen</term>
- <listitem><para>Pretend the pointer is a touchscreen device</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>updates</term>
- <listitem><para>Visual feedback about window updates</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>resize</term>
- <listitem><para>Highlight resizing widgets</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>layout</term>
- <listitem><para>Show layout borders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>snapshot</term>
- <listitem><para>Include debug render nodes in the generated snapshots</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara id="gtk-path">
- <title><envar>GTK_PATH</envar></title>
-
- <para>
- Specifies a list of directories to search when GTK is looking for
- dynamically loaded objects such as input method
- modules and print backends. If the path to
- the dynamically loaded object is given as an absolute path name,
- then GTK loads it directly.
- Otherwise, GTK goes in turn through the directories in <envar>GTK_PATH</envar>,
- followed by the directory <filename>.gtk-4.0</filename> in the user's
- home directory, followed by the system default directory,
- which is <filename><replaceable>libdir</replaceable>/gtk-4.0/modules</filename>.
- (If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
- <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
- specified when GTK was configured, usually
- <filename>/usr/lib</filename>, or
- <filename>/usr/local/lib</filename>.)
- For each directory in this list, GTK actually looks in a
- subdirectory
- <filename><replaceable>directory</replaceable>/<replaceable>version</replaceable>/<replaceable>host</replaceable>/<replaceable>type</replaceable></filename>
- Where <replaceable>version</replaceable> is derived from the
- version of GTK (use <literal>pkg-config
- --variable=gtk_binary_version gtk4</literal> to determine this from a
- script), <replaceable>host</replaceable> is the architecture on
- which GTK was built. (use <literal>pkg-config
- --variable=gtk_host gtk4</literal> to determine this from a
- script), and <replaceable>type</replaceable> is a directory
- specific to the type of modules; currently it can be
- <literal>modules</literal>, <literal>engines</literal>,
- <literal>immodules</literal>, <literal>filesystems</literal> or
- <literal>printbackends</literal>, corresponding to the types of
- modules mentioned above. Either <replaceable>version</replaceable>,
- <replaceable>host</replaceable>, or both may be omitted. GTK looks
- first in the most specific directory, then in directories with
- fewer components.
- The components of GTK_PATH are separated by the ':' character on
- Linux and Unix, and the ';' character on Windows.
- </para>
- <warning>
- Note that this environment variable is read by GTK 2.x and GTK 3.x too,
- which makes it unsuitable for setting it system-wide (or session-wide),
- since doing so will cause applications using different GTK versions
- to see incompatible modules.
- </warning>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_IM_MODULE</envar></title>
-
- <para>
- Specifies an IM module to use in preference to the one determined
- from the locale. If this isn't set and you are running on the system
- that enables <literal>XSETTINGS</literal> and has a value in
- <literal>Gtk/IMModule</literal>, that will be used for the default
- IM module.
- This also can be a colon-separated list of input-methods, which
- GTK will try in turn until it finds one available on the system.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_EXE_PREFIX</envar></title>
-
- <para>
- If set, GTK uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of
- the libdir configured when GTK was compiled.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_DATA_PREFIX</envar></title>
-
- <para>
- If set, makes GTK use <filename>$GTK_DATA_PREFIX</filename>
- instead of the prefix configured when GTK was compiled.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_THEME</envar></title>
-
- <para>
- If set, makes GTK use the named theme instead of the theme
- that is specified by the gtk-theme-name setting. This is intended
- mainly for easy debugging of theme issues.
- </para>
- <para>
- It is also possible to specify a theme variant to load, by appending
- the variant name with a colon, like this: `GTK_THEME=Adwaita:dark`.
- </para>
-</formalpara>
-
-<para>
-The following environment variables are used by GdkPixbuf, GDK or
-Pango, not by GTK itself, but we list them here for completeness
-nevertheless.
-</para>
-
-<formalpara>
- <title><envar>GDK_PIXBUF_MODULE_FILE</envar></title>
-
- <para>
- Specifies the file listing the GdkPixbuf loader modules to load.
- This environment variable overrides the default value
- <filename><replaceable>libdir</replaceable>/gtk-4.0/4.0.0/loaders.cache</filename>
- (<replaceable>libdir</replaceable> is the sysconfdir specified when
- GTK was configured, usually <filename>/usr/local/lib</filename>.)
- </para>
- <para>
- The <filename>loaders.cache</filename> file is generated by the
- <command>gdk-pixbuf-query-loaders</command> utility.
- </para>
- </formalpara>
-
-<formalpara id="GDK-Debug-Options">
- <title><envar>GDK_DEBUG</envar></title>
-
- <para>
- Unless GTK has been configured with <option>-Ddebug=false</option>,
- this variable can be set to a list of debug options, which cause GDK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>cursor</term>
- <listitem><para>Information about cursor objects (only win32)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>eventloop</term>
- <listitem><para>Information about event loop operation (mostly Quartz)</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>misc</term>
- <listitem><para>Miscellaneous information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>frames</term>
- <listitem><para>Information about the frame clock</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>settings</term>
- <listitem><para>Information about xsettings</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>selection</term>
- <listitem><para>Information about selections</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>clipboard</term>
- <listitem><para>Information about clipboards</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>dnd</term>
- <listitem><para>Information about drag-and-drop</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>opengl</term>
- <listitem><para>Information about OpenGL</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Information about Vulkan</para></listitem>
- </varlistentry>
- </variablelist>
- A number of options affect behavior instead of logging:
- <variablelist>
- <varlistentry>
- <term>nograbs</term>
- <listitem><para>Turn off all pointer and keyboard grabs</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-disable</term>
- <listitem><para>Disable OpenGL support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-software</term>
- <listitem><para>Force OpenGL software rendering</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-texture-rect</term>
- <listitem><para>Use the OpenGL texture rectangle extension, if available</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-legacy</term>
- <listitem><para>Use a legacy OpenGL context</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>gl-gles</term>
- <listitem><para>Use a GLES OpenGL context</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-disable</term>
- <listitem><para>Disable Vulkan support</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-validate</term>
- <listitem><para>Load the Vulkan validation layer, if available</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara id="GSK-Debug-Options">
- <title><envar>GSK_DEBUG</envar></title>
-
- <para>
- Unless GTK has been configured with <option>-Ddebug=false</option>,
- this variable can be set to a list of debug options, which cause GSK
- to print out different types of debugging information.
- <variablelist>
- <varlistentry>
- <term>renderer</term>
- <listitem><para>General renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>cairo</term>
- <listitem><para>cairo renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>opengl</term>
- <listitem><para>OpenGL renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>shaders</term>
- <listitem><para>Shaders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>ssurface</term>
- <listitem><para>Surfaces</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Vulkan renderer information</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>fallback</term>
- <listitem><para>Information about fallbacks</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>glyphcache</term>
- <listitem><para>Information about glyph caching</para></listitem>
- </varlistentry>
- </variablelist>
- A number of options affect behavior instead of logging:
- <variablelist>
- <varlistentry>
- <term>diff</term>
- <listitem><para>Show differences</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>geometry</term>
- <listitem><para>Show borders</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>full-redraw</term>
- <listitem><para>Force full redraws for every frame</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>sync</term>
- <listitem><para>Sync after each frame</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-staging-image</term>
- <listitem><para>Use a staging image for Vulkan texture upload</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>vulkan-staging-buffer</term>
- <listitem><para>Use a staging buffer for Vulkan texture upload</para></listitem>
- </varlistentry>
- </variablelist>
- The special value <literal>all</literal> can be used to turn on all
- debug options. The special value <literal>help</literal> can be used
- to obtain a list of all supported debug options.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_BACKEND</envar></title>
-
- <para>
- If set, selects the GDK backend to use. Selecting a backend requires that
- GTK is compiled with support for that backend. The following backends can
- be selected, provided they are included in the GDK libraries you are using:
- <variablelist>
-
- <varlistentry>
- <term>quartz</term>
- <listitem><para>Selects the native Quartz backend</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>win32</term>
- <listitem><para>Selects the native backend for Microsoft Windows</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>x11</term>
- <listitem><para>Selects the native backend for connecting to X11 servers.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>broadway</term>
- <listitem><para>Selects the Broadway backend for display in web browsers</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>wayland</term>
- <listitem><para>Selects the Wayland backend for connecting to Wayland display servers</para></listitem>
- </varlistentry>
-
- </variablelist>
- This environment variable can contain a comma-separated list of backend names,
- which are tried in order. The list may also contain a *, which means: try all
- remaining backends. The special value "help" can be used to make GDK print out
- a list of all available backends. For more information about selecting backends,
- see the gdk_display_manager_get() function.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GDK_VULKAN_DEVICE</envar></title>
-
- <para>
- This variable can be set to the index of a Vulkan device to override the
- default selection of the device that is used for Vulkan rendering.
- The special value <literal>list</literal> can be used to obtain a list
- of all Vulkan devices.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GSK_RENDERER</envar></title>
-
- <para>
- If set, selects the GSK renderer to use. The following renderers can
- be selected, provided they are included in the GTK library you are using
- and the GDK backend supports them:
- <variablelist>
-
- <varlistentry>
- <term>help</term>
- <listitem><para>Prints information about available options</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>broadway</term>
- <listitem><para>Selects the Broadway-backend specific renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>cairo</term>
- <listitem><para>Selects the fallback Cairo renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>gl</term>
- <listitem><para>Selects the default OpenGL renderer</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>vulkan</term>
- <listitem><para>Selects the Vulkan renderer</para></listitem>
- </varlistentry>
-
- </variablelist>
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>GTK_CSD</envar></title>
-
- <para>
- The default value of this environment variable is 1. If changed to 0, this
- disables the default use of client-side decorations on GTK windows, thus
- making the window manager responsible for drawing the decorations of
- windows that do not have a custom titlebar widget.
- </para>
- <para>
- CSD is always used for windows with a custom titlebar widget set, as the WM
- should not draw another titlebar or other decorations around the custom one.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
-
- <para>
- GTK uses these environment variables to locate icon themes
- and MIME information. For more information, see
- <ulink url="https://freedesktop.org/Standards/icon-theme-spec">Icon Theme Specification</ulink>,
- the <ulink url="https://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
- and the <ulink url="https://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
- </para>
-</formalpara>
-
-<formalpara>
- <title><envar>DESKTOP_STARTUP_ID</envar></title>
-
- <para>
- GTK uses this environment variable to provide startup notification
- according to the <ulink url="https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">Startup Notification Spec</ulink>.
- Following the specification, GTK unsets this variable after reading
- it (to keep it from leaking to child processes). So, if you need its
- value for your own purposes, you have to read it before calling
- gtk_init().
- </para>
-</formalpara>
-
-</refsect2>
-
-<refsect2 id="interactive-debugging">
-<title>Interactive debugging</title>
-
- <inlinegraphic fileref="inspector.png" format="PNG"></inlinegraphic>
-
- <para>
- GTK includes an interactive debugger, called the GTK Inspector, which
- lets you explore the widget tree of any GTK application at runtime, as
- well as tweak the theme and trigger visual debugging aids. You can
- easily try out changes at runtime before putting them into the code.
- </para>
- <para>
- Note that the GTK inspector can only show GTK internals. It can not
- understand the application-specific logic of a GTK application. Also,
- the fact that the GTK inspector is running in the application process
- limits what it can do. It is meant as a complement to full-blown debuggers
- and system tracing facilities such as DTrace, not as a replacement.
- </para>
- <para>
- To enable the GTK inspector, you can use the Control-Shift-I or
- Control-Shift-D keyboard shortcuts, or set the
- <envar>GTK_DEBUG=interactive</envar> environment variable.
- </para>
- <para>
- There are a few more environment variables that can be set to influence
- how the inspector renders its UI. <envar>GTK_INSPECTOR_DISPLAY</envar> and
- <envar>GTK_INSPECTOR_RENDERER</envar> determine the GDK display and
- the GSK renderer that the inspector is using.
- </para>
-
- <para>
- In some situations, it may be inappropriate to give users access to the
- GTK inspector. The keyboard shortcuts can be disabled with the
- `enable-inspector-keybinding` key in the `org.gtk.Settings.Debug`
- GSettings schema.
- </para>
-
-</refsect2>
-
-<refsect2 id="profiling">
- <title>Profiling</title>
-
- <para>
- GTK supports profiling with sysprof. It exports timing information
- about frameclock phases and various characteristics of GskRenders
- in a format that can be displayed by sysprof or GNOME Builder.
- </para>
- <para>
- A simple way to capture data is to set the <envar>GTK_TRACE</envar>
- environment variable. When it is set, GTK will write profiling
- data to a file called
- <filename>gtk.<replaceable>PID</replaceable>.syscap</filename>.
- </para>
- <para>
- When launching the application from sysprof, it will set the
- <envar>SYSPROF_TRACE_FD</envar> environment variable to point
- GTK at a file descriptor to write profiling data to.
- </para>
- <para>
- When GtkApplication registers with D-Bus, it exports the
- <literal>org.gnome.Sysprof2.Profiler</literal> interface
- that lets sysprof request profiling data at runtime.
- </para>
-</refsect2>
-
-</refsect1>
-
-</refentry>
projects / gtk4.git / commitdiff